…ling

External-developer receiver that borrows canonical sBTC from flashstack-sbtc-core, performs a real Velar sBTC -> wSTX -> sBTC round-trip (pool 70), and repays principal + fee atomically. The sBTC counterpart to the STX/Bitflow receiver.

Contract (contracts/hk-sbtc-real-receiver-v1.clar):

• caller gate: asserts contract-caller == flashstack-sbtc-core (err u403), closing the direct-drain path a public callback would expose
• dynamic fee lookup (no hard-coded basis points)
• min-out=u1 swap legs with a fail-closed repayment assert; the core's before/after reserve check is the ultimate safety gate (reserve never at risk)
• owner-only rescue-sbtc / rescue-wstx; read-only estimate-repayment
• absolute mainnet principals throughout; literal principals for the Velar router's trait-reference arguments

Tooling (all DRY_RUN-aware with preflight checks):

• deploy-hk-sbtc-receiver.mjs deploy from an external wallet
• seed-hk-sbtc-receiver.mjs SIP-010 sBTC seed transfer
• execute-sbtc-flash-loan.mjs flash loan with approval/reserve/seed preflight
• buy-sbtc.mjs acquire the sBTC seed on Velar

Docs:

• minimum_seed_analysis.md seed sizing from live pool-70 reserves
• hk-sbtc-receiver-deployment-plan.md ADRs, validation record, runbook
• sbtc-architecture-review.md sBTC engine mapping + live-state findings

Validation (off-chain): clarinet check passes against logic-equivalent stubs; caller-gate negative test returns (err u403); deploy/seed/execute/buy scripts build successfully in DRY_RUN against live mainnet reads. No mainnet transactions performed: deployment, whitelisting, and execution remain pending.

Description

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🧪 Test addition or improvement
• 🔧 Refactoring (no functional changes)
• 🎨 Style/formatting changes
• ⚡ Performance improvement

Related Issues

Fixes #
Related to #

Changes Made

Testing Performed

Manual Testing

• Tested locally with clarinet check
• Tested in clarinet console
• Tested specific edge cases

Automated Testing

• All existing tests pass
• Added new tests for changes
• Tests cover edge cases

Test Commands Run

# List the commands you ran to test
clarinet check
clarinet console3

Test Results

# Paste test output here

Checklist

Code Quality

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• Any dependent changes have been merged and published

Documentation

• I have updated the documentation accordingly
• I have updated the README.md (if needed)
• I have added/updated code comments
• I have updated the CHANGELOG.md

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested edge cases
• I have tested error conditions

Security & Safety

• My changes don't introduce security vulnerabilities
• I haven't committed any secrets or sensitive data
• I've considered the impact on existing users
• I've followed Clarity best practices

Screenshots (if applicable)

Additional Context

Deployment Considerations

• Requires contract deployment
• Requires data migration
• Requires configuration changes
• Backward compatible

By submitting this PR, I confirm that:

• My contribution is made under the MIT License
• I have read and followed the CONTRIBUTING.md guidelines
• I am the original author or have permission to contribute this code